ETO Development Tools 2

home *** CD-ROM | disk | FTP | other *** search

/ ETO Development Tools 2 / ETO Development Tools 2.iso / Essentials / Developer Essentials Nov 90 / Apple II / Apple.II.partition / Tools / Technical.Notes / IIGS / TN.IIGS.053 < prev next >

Wrap

Text File | 1990-09-21 | 14.6 KB | 284 lines | [TEXT/pdos]

Apple II Technical Notes _____________________________________________________________________________ Developer Technical Support Apple IIgs #53: Desk Accessories and Tools Revised by: Dave Lyons September 1990 Written by: Matt Deatherage & Jim Mensch March 1989 This Technical Note discusses compatibility issues that can arise between desk accessories and applications. Where possible, it presents solutions. Changes since November 1989: Added to the discussions of Close with reference number zero and of when applications should start and shut down tools. Noted that StartUpTools is not intended to be called from an NDA. _____________________________________________________________________________ Desk accessories vary widely in complexity. Classic Desk Accessories (CDAs) range from simple status-reporting programs to complete system-level debugging utilities, and similarly, New Desk Accessories (NDAs) range from static windows with pictures to nearly full-fledged applications. This Note presents some new guidelines aimed at helping developers of both applications and desk accessories to get their products to work together now and in the future. Tool Sets The greatest conflict between applications and desk accessories, especially NDAs, is the use of system tool sets. The Apple IIgs Toolbox Reference, Volume 1, defines which tools are available for use by NDAs. The Desk Manager requires starting the following tool sets before calling FixAppleMenu (which installs the names of the NDAs in the Apple menu): Tool Locator (#1) Memory Manager (#2) Miscellaneous Tools (#3) QuickDraw II (#4) Event Manager (#6) Window Manager (#14) Menu Manager (#15) Control Manager (#16) LineEdit (#20) Dialog Manager (#21) Scrap Manager (#22) Since the Desk Manager requires starting these tools before calling FixAppleMenu, NDAs may assume that these tools are all present and running, so they do not need to check for their presence. In addition to these requirements by the Desk Manager, Apple strongly recommends that all applications start the following tools: QuickDraw Auxiliary (#18) Font Manager (#27) These two additional tools are so widely used by desk accessories that they should be present. NDAs may not assume their presence, but it is reasonable to write an NDA that checks for them, with the assumption that they usually turn out to be available. The Golden NDA Guideline Developers who wish to maintain maximum compatibility between their NDAs and applications, both now and in the future, should consider every environment change they make with the following Golden NDA Guideline firmly in mind: "I, an NDA, pledge not to alter the environment of the application under which I run, and I will behave in such a way that the application runs the same whether I am present or not." Of course, this guideline does not include such necessary tasks as the normal (and reasonable) allocation of memory. An application must be prepared to handle a memory allocation call by a desk accessory, operating system, or even a tool at unexpected times. The guideline does, however, mean that your desk accessory cannot change the operating environment, including such things as the presence of tools and operating system parameters. The following sections detail some of the most important ways to follow the Golden NDA Guideline. Desk Accessory Guidelines Extra Tools o If an NDA needs to use a tool which is not guaranteed to be available (e.g., Standard File), it should check to see if the tool is already running. If it is not running, the NDA must use LoadOneTool to load it, then it must start the tool before using it. When finished with the tool, the NDA must shut it down and unload it with UnloadOneTool. (A tool is already running if its xxxStatus function returns TRUE and no error.) o If an NDA needs to start up a tool and keep it started while letting the application continue to run, things quickly get complicated. If your NDA starts a tool which the application is going to use but has not yet started (i.e., the Font Manager), and your NDA does not shut it down before the application regains control, the application (in this example) gets error $1B01 (Font Manager Already Started) when it makes an FMStartUp call. Many applications stop gracelessly on getting a tool startup error. A previous version of this Note advised NDAs to start up and shut down tools when their windows were activated and deactivated. This approach isn't strong enough to solve all the problems, since the application may decide to start up tools based on menu items (which can still be selected while an NDA window is in front). The only completely safe way to use a tool that isn't already running is to start it, use it, and shut it back down without ever returning control to the application while the tool set is started. Starting QuickDraw Auxiliary when the application has not started it can get you into a lot of trouble: an application that correctly implements 320/640 mode switching calls QDShutDown and QDStartUp. QuickDraw Auxiliary depends heavily on QuickDraw, and restarting QuickDraw while QuickDraw Auxiliary is active easily toasts you. o StartUpTools is designed to be called only by an application, not a desk accessory. Unexpected things happen if your NDA calls StartUpTools (for example, you may get a second copy of the application's resource fork open in your NDA's private resource search path; this wastes RAM and can interfere with an application's attempt to write to its own resource fork). For now, do not call StartUpTools from a DA. o If your NDA allocates bank-zero work area space for tool sets, be sure to dispose of it at DeskShutDown time (when your DAInit entry is called for shutdown). If you don't, the system dies with error $0201 when trying to launch a ProDOS 8 application, since GS/OS needs all of banks 0 and 1 to start ProDOS 8. o Sound tools are an exception to the rule of freely using a tool which is already started. Refer to the section on System Parameters for more details on using sound tools. o NDAs must not shut down tools which they have not started. o CDAs are nearly always modal, but by using the HeartBeat interrupt queue or other mechanisms, they can get control when the user is no longer "in" the CDA. The list of guaranteed tools for NDAs does not apply to CDAs, and CDAs must be prepared to deal with the ProDOS 8 environment as well as GS/OS. System Parameters o A desk accessory (CDA or NDA) must not change a system resource or parameter which cannot be restored to its original condition. A trivial, but illustrative, example of this is the number of times a pull-down menu item blinks when you select it. This number (three by default) may be changed with the SetMItemBlink call, but there is no corresponding GetMItemBlink call, so you cannot retrieve the current value. Therefore, a desk accessory must not change this parameter, and the same rule applies to any other system parameter for which you cannot determine a current value. o This idea extends to calling tool startup functions. Even though a tool's startup function may not return an error when the tool is already active, the startup function could reset certain parameters upon which the application depends. An example of this is TLStartUp for the Tool Locator. A seemingly innocuous call, TLStartUp actually disconnects any user tool sets present, which, in this case, would most likely have been installed by the current application. CDAs and NDAs must never call TLStartUp or TLShutDown. A desk accessory should generally not call a tool's startup function if the tool is already active. Two exceptions are (1) the Memory Manager's MMStartUp call, which you can think of as a "GetMyID" call, and (2) ResourceStartUp, because the Resource Manager needs to be started up explicitly by each client (see Apple IIgs Technical Note #71, Desk Accessory Tips and Techniques). o A desk accessory cannot use any of the sound tools if they are already started. This is contrary to the rule for other tool sets, but it is required because there is no memory management of the sound RAM (or "DOC RAM"). If the Sound Tools (#8) are started, the application has exclusive control of the 64K DOC RAM used to play sounds. Anything your desk accessory might put there could overwrite information the application needs. Saving and restoring DOC RAM around desk accessory usage is not sufficient. Many of the sound functions are interrupt driven, altering the contents of DOC RAM only during sound interrupts, so your desk accessory might attempt to replace parts of DOC RAM which are being played. Since there is no memory management of DOC RAM, desk accessories must avoid the sound functions of the IIgs if the application is already using them. o A desk accessory must not install user tool sets, because there is no arbitration of user tool set numbers. User tool sets are the sole property of the current application. A desk accessory should not call user tool sets even if it determines that the host application has installed a certain tool set, because that limits future system software options. For example, consider a hypothetical multiple-application environment. If DAs call user tool sets and the system automatically switches between separate collections of user tool sets, there would be no way for the system to know which set to switch in before giving control to a desk accessory. Application Guidelines To coexist peacefully with desk accessories, particularly NDAs, applications need to follow the guidelines listed in the Desk Manager chapter of the Apple IIgs Toolbox Reference, Volume 1. However, those applications which wish to ensure maximum compatibility now and in the future also want to adhere to the following: o Be careful about when your application starts and shuts down tools. A highly compatible approach is to start tools at the beginning of your application and leave them started. For certain tools, like Standard File, it is reasonable to load and start the tool set each time it's needed (you may want to check whether it's already started, in case some impolite NDA started Standard File and left it started). Note that UnloadOneTool followed later by LoadOneTool does not necessarily cause disk access or ask the user to insert the boot disk. UnloadOneTool calls UserShutDown to put the tool set into "zombie" state, where it can be restarted from memory if none of its segments have been purged. Unloading tools while they aren't in use is a Good Thing--if the user has plenty of RAM, there's no noticeable performance hit, but if RAM space is tight then doing extra disk access is preferable to actually running out of memory. For maximum compatibility, an application should not shut down any tools which were ever active when you called SystemTask or TaskMaster (until quitting time, of course, when you shut down everything, starting with the Desk Manager). You can start more tools, but do not shut down those which are already active. If you intend to start a tool and not keep it started, use it and then shut it down immediately, being sure not to call SystemTask or TaskMaster during that time. Future system software may provide arbitration of tool set use, but for now these guidelines provide a solution with which you can work. o Don't just start the Scrap Manager--use it! Many desk accessories support cutting and pasting to exchange text and pictures with your application, but they can do it only if you use the Scrap Manager. If you have a need for your own private scrap internally, you should still also use the Scrap Manager to exchange text and pictures with other applications and DAs. o Applications should not call CloseAllNDAs while shutting down. Since DeskShutDown closes all open NDAs anyway, it's not necessary. By not calling CloseAllNDAs, you allow the system or NDAs to tell the difference between just cleaning up and really wanting to close all the NDAs. o Applications should never make a Close call with reference number zero at file level zero. (If you need to use Close with reference number zero, use GetLevel and SetLevel to avoid closing files you did not open. Desk accessories should open files at level zero to ensure their files stay open when a DA-friendly application is using this scheme.) It would be good if the system provided Desk Accessories with a way to open files and be certain that an application can never close them by accident, but for now this is a solution with which you can work. o An application with some memory to spare can save NDAs time by providing them the additional tools which they are most likely to use. If a desk accessory needs the List Manager and your application starts it, the desk accessory runs faster since it can avoid loading and starting the tool every time it gets control. The most common tools which desk accessories require besides those available in the standard Desk Manager set are QuickDraw Auxiliary (#18), the Print Manager (#19), Standard File (#23), the Font Manager (#27), and the List Manager (#28). QuickDraw Auxiliary and the Font Manager are especially important--not only do they work well together, but they are also widely used. In addition, FMStartUp can take a long time, and waiting for it every time you activate an NDA window can be really frustrating. Many desk accessories also use the Print Manager, the List Manager, and Standard File, and if they are always available, desk accessories work more smoothly with your application. Further Reference: _____________________________________________________________________________ o Apple IIgs Toolbox Reference o Programmer's Introduction to the Apple IIgs o Apple IIgs Technical Note #71, Desk Accessory Tips and Techniques